This made me wonder about the details of how a deadlock could occur, so that one can avoid it properly. Seemed to suggest Executor tasks are executed in order, of submission perhaps, so I was thinking maybe a task waiting for the future is put on the queue first. But that would mean a caller queues the future task before the task that it waits on. Is that really the scenario, or is there something else at play?

In short, if you could elaborate on the particulars of how the deadlock can happen, that would help readers not to do it.

I don't think execution order matters (although yes the queue is FIFO). It's just what it says: blocking generic threads on futures risks deadlock if the completion of those futures requires work to be done on the generic pool. There's no way to do that work if all the threads that could do it are blocked.

Thanks for referencing UnsafePlainActionFuture 👍

I'd bump this paragraph higher, swap it with the above deadlock paragraph. It looks like a natural continuation of the CPU/IO paragraphs discussions, and deadlocking doesn't participate in that line of reasoning (but currently interrupts it).

I left it where it is but clarified that recovery also doesn't block on futures, so this now follows more logically from the preceding paragraphs.

looks good 👍